Add a tutorial to deploy Keycloak in cluster mode by Frzk · Pull Request #3622 · Scalingo/documentation

Frzk · 2026-03-23T14:29:49Z

No description provided.

EtienneM

praise: that's great, I don't have much to say about this :)

EtienneM · 2026-03-27T09:37:19Z

+This tutorial covers the deployment of Keycloak on Scalingo. Configuring,
+managing, and administrating Keycloak is out of the scope of this tutorial.


suggestion: add a link to the Keycloak documentations for these?

I've added some in 660662f

EtienneM · 2026-03-27T09:40:10Z

+5. (optional) Create credentials for the initial administrator user:
+   ```bash
+   scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_USERNAME=<admin_username>
+   scalingo --app my-keycloak env-set KC_BOOTSTRAP_ADMIN_PASSWORD=<admin_password>
+   ```


question: what is the admin password if we don't set this? If it's insecure to not set an admin password, I would mark this step as mandatory

You're right, I've made them mandatory (well they technically aren't but they are if you follow the doc) in c57358e

If the user don't create them, Keycloak will ask them to create one... but the interface is only available on localhost. So it won't work.

EtienneM · 2026-03-27T09:48:23Z

+
+- Review the official changelog that is published with each release. Breaking
+  and notable changes should catch your attention.
+- Ensure your SPIs and themes are compatible with the new version.


question: what is a SPI?

I've added a link to the little explanation we have in ffd9547

EtienneM · 2026-03-27T09:50:10Z

+Moreover, the buildpack makes use of the following environment variables. They
+can be leveraged to customize your deployment:
+
+- `KEYCLOAK_VERSION`\\


question: that makes me think: do we have a NewReleases configuration to track Keycloak releases?

I don't think so.
Actually, updating the default version in the buildpack is something I'd like to automate through GitHub Action.
In the meantime, and until it's done, you're right, let's add it :)

Co-authored-by: Étienne M. <EtienneM@users.noreply.github.com>

SPIs are ~explained in the Customizing section.

semgrep-code-scalingo · 2026-05-06T12:57:47Z

Legal Risk

The following dependencies were released under a license that
has been flagged by your organization for consideration.

Recommendation

While merging is not directly blocked, it's best to pause and consider what it means to use this license before continuing. If you are unsure, reach out to your security team or Semgrep admin to address this issue.

MPL-2.0

yanjost

One security flag on the nginx sample — happy to chat about the exact Scalingo router CIDR if useful.

yanjost · 2026-06-12T08:33:46Z

+  charset utf-8;
+
+  # Optional hardening:
+  proxy_hide_header X-Powered-By;


issue (high — security): this nginx sample doesn't set any X-Forwarded-* headers, but step 5 above mandates KC_PROXY_HEADERS=xforwarded, which tells Keycloak to trust the incoming X-Forwarded-For verbatim for client-IP resolution.

nginx's default is to forward whatever X-Forwarded-For the downstream sent — so a remote client can just set X-Forwarded-For: 8.8.8.8 (rotating values too) and Keycloak will attribute the request to that fake IP. This defeats:

the per-IP brute-force / loginFailures counter;

realm-level IP allow/deny policies;

audit-log forensics on clientAddress;

any downstream SIEM rule keyed on Keycloak's reported source IP.

Suggested additions in the server { … } block (around the # Optional hardening: lines):

Suggested change

proxy_hide_header X-Powered-By;

# Optional hardening:

proxy_hide_header X-Powered-By;

# Trust only the Scalingo router for real-IP / XFF rewriting.

# Replace with the documented Scalingo router CIDR(s).

# set_real_ip_from <scalingo-router-CIDR>;

# real_ip_header X-Forwarded-For;

# real_ip_recursive on;

proxy_set_header Host $host;

proxy_set_header X-Real-IP $remote_addr;

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Proto $scheme;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Port $server_port;

To verify afterwards: send a request with a forged X-Forwarded-For header, then check clientAddress in the Keycloak admin event log — it should show your real source IP, not the forged one.

questions:

Isn't X-Forwarded-For set by our frontend reverse proxies?

If this is a security flaw, shouldn't we better put these settings in our default nginx config file (the one provided by our buildpack)?

Can you provide the Scalingo routers CIDRs?

Thanks!

Frzk added 6 commits March 23, 2026 13:00

feat(getting-started): introduce Getting Started With Keycloak

b5c3cb0

chore: move Keycloak guide in a single file

d694180

chore(tutorials): move Keycloak to tutorials

7090858

feat(tutorial): update Keycloak tutorial

6419f6b

feat(tutorial): update Keycloak tutorial

3ac7dfe

feat(tutorial): update Keycloak tutorial

5691391

Frzk self-assigned this Mar 26, 2026

EtienneM self-requested a review March 26, 2026 13:21

fix(tutorial): update wording in Keycloak tutorial

8c12ac8

EtienneM requested changes Mar 27, 2026

View reviewed changes

Frzk and others added 5 commits March 27, 2026 11:23

fix: apply suggestions from code review

c528956

Co-authored-by: Étienne M. <EtienneM@users.noreply.github.com>

fix: add a link on the first SPI mention

ffd9547

SPIs are ~explained in the Customizing section.

fix: make KC_BOOTSTRAP_ADMIN_{USERNAME|PASSWORD} mandatory

c57358e

fix: add some links to Keycloak's doc

660662f

feat(tuto): add a disclaimer for Keycloak tutorial

8e6342b

Frzk added 3 commits May 6, 2026 15:29

Merge branch 'master' into feat/keycloak

e71dadd

feat: apply req. from internal review

42ce131

chore: remove paragraph about Java version

e0fc588

yanjost reviewed Jun 12, 2026

View reviewed changes

		This tutorial covers the deployment of Keycloak on Scalingo. Configuring,
		managing, and administrating Keycloak is out of the scope of this tutorial.

-  proxy_hide_header X-Powered-By;
+  # Optional hardening:
+  proxy_hide_header X-Powered-By;
+  # Trust only the Scalingo router for real-IP / XFF rewriting.
+  # Replace with the documented Scalingo router CIDR(s).
+  # set_real_ip_from <scalingo-router-CIDR>;
+  # real_ip_header X-Forwarded-For;
+  # real_ip_recursive on;
+  proxy_set_header Host              $host;
+  proxy_set_header X-Real-IP         $remote_addr;
+  proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
+  proxy_set_header X-Forwarded-Proto $scheme;
+  proxy_set_header X-Forwarded-Host  $host;
+  proxy_set_header X-Forwarded-Port  $server_port;

Conversation

Frzk commented Mar 23, 2026

Uh oh!

EtienneM left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

semgrep-code-scalingo Bot commented May 6, 2026

Legal Risk

Recommendation

Uh oh!

yanjost left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants